refactor(server): interest-counted module compile cancellation - #454

Background

clice compiles C++20 module dependencies through CompileGraph: each module interface unit is a node, resolve lazily discovers its imports, and dispatch builds the PCM. Overlapping dependency closures are the normal case — two open files importing different modules that share a common dependency.

The previous cancellation model propagated cancellation through a token tree: a requester wrapped every dependency task in with_token(...) of its own source, recursively, and dependency compilations ran nested inside the requester's coroutine frames. That model has a structural mismatch with the problem:

1. Dependencies form a DAG; token trees are trees. With A → B → E and C → D → E, E's compilation runs inside whichever request got there first — say A's. Cancelling the A request tears down its whole coroutine tree and kills E's in-flight build, even though the C request still needs it. There was no notion of "who else is interested in E".
2. Two unrelated cancellation reasons shared one mechanism. "This request no longer needs the result" (request cancelled, import switched away) and "the source changed on disk, the in-flight result is garbage" (file update) were both expressed as source->cancel() inside update(), entangled with dirty-marking.
3. Waiters treated every cancellation as failure. A waiter woken by a cancelled compilation returned failure, even when the right reaction was "the result went stale — retry with the new content".

Design

The core shift: execution is decoupled from interest.

Execution — each dirty unit compiles in an independent task spawned into a graph-owned task_group, cancellable only through its own per-round token. Requesters and dependent units no longer own child coroutine frames; they wait on a per-round completion event. A requester dying implies nothing, by itself, about the units it was waiting on.

Interest — an explicit per-unit count of in-flight demand: a request holds a root reference on the unit(s) it asked for; a running unit task holds an edge reference on each direct dependency. A unit whose count stays at zero for one event-loop tick while compiling has its round cancelled. The one-tick deferral matters: an interest drop is often transient — a stale round's edges being re-acquired by the retry that re-resolves it — and synchronous re-acquisition always lands within the same drain cycle, strictly before the deferred check fires. So when a unit's import set changes from {B, C} to {B, E} mid-compile, the retained B is handed over to the new round (neither cancelled nor restarted, at any cascade depth), while the orphaned C is cancelled one tick later. Cancellation cascades structurally — the dying task's guard releases its edge references, which may zero out further dependencies — and stops exactly where shared interest remains: cancel the A request and A, B unwind while E drops 2 → 1 and keeps compiling.

Edge references were chosen over counting each request's transitive closure deliberately: the closure is lazily discovered (resolve runs on first compile), so closure-counting would need per-request acquired-sets with incremental backfill as resolution proceeds. Edge counting needs zero global bookkeeping and yields the same outcomes.

The two cancellation reasons are now distinct operations:

• Loss of interest (reference-driven): release → zero → cancel that unit's round. "Nobody needs this."
• Staleness (update()): mark the unit and its transitive dependents dirty, bump their generation, cancel their in-flight rounds unconditionally — interest untouched. "The source changed; the results are garbage, but everybody still wants them."

What a waiter does next is decided by a three-state round outcome rather than a boolean:

• Success → done.
• Failed (compile error, dependency cycle) → propagate failure, never retry: retrying failures would turn an A↔B cycle or a plain syntax error into a retry storm.
• Stale (round cancelled) → a waiter that still holds interest becomes the new driver and respawns the unit. Retries are naturally bounded — each consumes one staleness event; no new update(), no further retry.

Cancellation safety

kotatsu cancels by frame destruction without resumption: a cancelled coroutine never executes another statement past its suspension point — only destructors of already-constructed locals run. All per-round bookkeeping therefore lives in a single scope guard constructed before the unit task's first suspension: publish the outcome (default stale — the cancel path can't reach an explicit assignment), clear the compiling flag, release acquired edge references (possibly cancelling zero-interest dependencies — a synchronous primitive, safe in a destructor), fire the completion event. Edge acquisition is likewise fully synchronous, so no suspension can strand a half-registered reference.

Two kotatsu behaviors shaped the implementation and are worth knowing for review:

• task_group is fail-fast structured concurrency: one child finishing Cancelled aborts every sibling and permanently blocks new spawns. Since a cancelled round is the normal case here, rounds are spawned through a thin wrapper that converts the cancellation into a value, so every child finishes Finished. (Found empirically by the shared-dependency tests: "cancelling A killed C's entire chain".)
• task_group reclaims child frames only at destruction, so frames accumulate one per round until shutdown — the same trade-off as the compiler's existing AST-compile group; documented in code as a candidate kotatsu-side improvement.

The import-switch handoff

The headline scenario: a file says import A, the build is in flight, the user switches to import C, and both chains share E. The old request's interest must go away — but if it disappears before the new request registers its own, E transits through zero and is killed and restarted anyway.

ensure_compiled therefore supersedes a stale in-flight compile in a fixed order: spawn the replacement first — it descends the new dependency chain and acquires interest synchronously (spawned tasks run to their first suspension immediately, while cancellation only lands on the next event-loop tick) — then cancel the superseded request's dependency scope. Interest on shared units overlaps across the swap; E never sees zero.

Reviewing this path surfaced two ordering hazards, both fixed here: a superseded compile re-checks the session generation before sending text to the stateful worker (the worker applies compiles in arrival order with no version check, so a stale send landing after the replacement would leave the worker on old text), and a superseded round abandons its remaining preparation instead of continuing into the PCH build.

Cycle handling

The old ancestor-set threading cannot survive the move to independent tasks — there is no call chain to thread it through. Cycles are caught where they manifest: a self-import directly after resolve, and a would-deadlock wait — before blocking on a dependency, the waiter walks currently-compiling units' dependency edges to check whether the chain leads back to itself. Detected cycles fail the unit (no retry), including cycles that only appear after update() re-resolves a changed import set. Surfacing them as file-level diagnostics is follow-up work.

Testing

The strategy is deterministic cancellation injection: a manually gated mock dispatch parks any unit mid-dispatch, the test observes interest counts at that instant, injects a request cancellation / update / shutdown, and asserts which compilations survived — by liveness, refcount, and dispatch-call counts, not just final success. Every test tears down through shutdown() and asserts the graph is fully quiesced (zero refcounts, no compiling residue, every completion fired); a fixed-seed randomized stress run interleaves compiles, cancellations, updates and completions with per-step structural checks.

Two integration cases run the headline scenarios against real clang module builds: switching the import target neither kills nor restarts the shared dependency (one dispatch, one PCM), and a shared dependency failing fails both consumers from a single round. Unit cases additionally pin down both cancellation directions of a shared dependency (stepwise refcount 2 → 1 → 0) and the in-flight import-set change (retained dependency handed over with a single dispatch, orphan cancelled and fully detached).

All pre-existing cases are preserved. One changes meaning intentionally: a file update during compilation used to fail the waiting request; it now retries once and succeeds, asserted by exact dispatch counts.

Verified locally on Debug and RelWithDebInfo: 615 unit / 172 integration / 2 smoke tests passing.

Summary by CodeRabbit

• Refactor

  • Reworked compilation lifecycle to per-round orchestration with deterministic cancellation, interest-counted dependency management, improved deadlock detection, generation-based supersession of in‑flight compiles, and structured shutdown that cancels and joins running work.

• New Features

  • Added runtime diagnostics to query per‑unit refcount/idle/consistency and support for per-request cancellation scopes and safer dependency await semantics.

• Tests

  • Expanded deterministic, concurrency, and shutdown tests covering shared dependencies, cancellation/retry, failure propagation, and graph consistency.